Section 3.1.8.3
String Functions

The following are the functions which take one or more string and float parameters and return string or float values. Assume that S1 and S2 are any valid strings and that A L and P are any valid expressions that evaluate to floats.

asc(S1): ASCII value of S1. Returns an integer value in the range 0 to 255 that is the ASCII value of the first character of S1. For example asc("ABC") is 65 because that is the value of the character "A".

chr(A): Character whose ASCII value is A. Returns a single character string. The ASCII value of the character is specified by an integer A which must be in the range 0 to 255. For example chr(70) is the string "F".

concat(S1,S2,[S3...]): Concatenate strings S1 and S2. Returns a string that is the concatenation of all parameter strings. Must have at least 2 parameters but may have more. For example:

concat("Value is ", str(A,3,1), " inches")

If the float value A was 12.34 the result is "Value is 12.3 inches" which is a string.

file_exists(S1): Search for file specified by S1. Attempts to open the file whose name is specified the string S1. The current directory and all directories specified in any Library_Path INI options or +L command line switches are searched. File is immediately closed. Returns a boolean value 1 on success and 0 on failure.

str(A,L,P): Convert float A to formatted string. Returns a formatted string representation of float value A. The float parameter L specifies the minimum length of the string and the type of left padding used if the string's representation is shorter than the minimum. If L is positive then the padding is with blacks. If L is negative then the padding is with zeros. The overall minimum length is of the formatted string is abs(L). If the string needs to be longer, it will be made as long as necessary to represent the value.

The float parameter P specifies the number of digits after the decimal point. If P is negative then a compiler-specific default precision is use. Here are some examples:

  str(123.456,0,3)   "123.456"  str(123.456,4,3)   "123.456"  str(123.456,9,3)   "  123.456"  str(123.456,-9,3)  "00123.456"  str(123.456,0,2)   "123.46"  str(123.456,0,0)   "123"  str(123.456,5,0)   "  123"  str(123.000,7,2)   " 123.00"  str(123.456,0,-1)  "123.456000" (platform specific)

strcmp(S1,S2): Compare string S1 to S2. Returns a float value zero if the strings are equal, a positive number if S1 comes after S2 in the ASCII collating sequence, else a negative number.

strlen(S1): Length of S1. Returns an integer value that is the number of characters in the string S1.

strlwr(S1): Lower case of S1. Returns a new string in which all upper case letters in the string S1 are converted to lower case. The original string is not affected. For example strlwr("Hello There!") results in "hello there!".

substr(S1,P,L): Sub-string from S1. Returns a string that is a subset of the characters in parameter S1 starting at the position specified by the integer value P for a length specified by the integer value L. For example substr("ABCDEFGHI",4,2) evaluates to the string "EF". If P+L>strlen(S1) an error occurs.

strupr(S1): Upper case of S1. Returns a new string in which all lower case letters in the string S1 are converted to upper case. The original string is not affected. For example strlwr("Hello There!") results in "HELLO THERE!".

val(S1): Convert string S1 to float. Returns a float value that is represented by the text in S1. For example val("123.45") is 123.45 as a float.

Section 3.2
Language Directives

The POV Scene Language contains several statements called language directives which tell the file parser how to do its job. These directives can appear in almost any place in the scene file --- even in the middle of some other statements. They are used to include other text files in the stream of commands, to declare identifiers, to define conditional or looped parsing and to control other important aspects of scene file processing.

Each directive begins with the hash character # (often called a number sign or pound sign). It is followed by a keyword and optionally other parameters.

In versions of POV-Ray prior to 3.0, the use of this # character was optional. Language directives could only be used between objects, camera or light_source statements and could not appear within those statements. The exception was the #include which could appear anywhere. Now that all language directives can be used almost anywhere, the # character is mandatory.

The following keywords introduce language directives.


#break              #default            #statistics
#case               #else               #switch
#debug              #end                #version
#declare            #render             #warning

Earlier versions of POV-Ray considered #max_intersections and #max_trace_level to be language directives but they have been moved to the global_settings statement. Their use as a directive still works but it generates a warning and may be discontinued in the future.

Section 3.2.1
Include Files

The language allows include files to be specified by placing the line:

#include "filename.inc"

at any point in the input file. The filename may be specified by any valid string expression but it usually is a literal string enclosed in double quotes. It may be up to 40 characters long (or your computer's limit), including the two double-quote (") characters.

The include file is read in as if it were inserted at that point in the file. Using include is the same as actually cutting and pasting the entire contents of this file into your scene.

Include files may be nested. You may have at most 10 nested include files. There is no limit on un-nested include files.

Generally, include files have data for scenes, but are not scenes in themselves. By convention scene files end in .pov and include files end with .inc.

It is legal to specify drive and directory information in the file specification however it is discouraged because it makes scene files less portable between various platforms.

It is typical to put standard include files in a special sub-directory. POV-Ray can only read files in the current directory or one referenced by the Library_Path option (See section "Library Paths" ).

Section 3.2.2
Declare

Identifiers may be declared and later referenced to make scene files more readable and to parametrize scenes so that changing a single declaration changes many values. There are several built-in identifiers which POV-Ray declares for you. See "Built-in Identifiers" for details.

Section 3.2.2.1
Declaring identifiers

An identifier is declared as follows.

#declare IDENTIFIER = ITEM

Where IDENTIFIER is the name of the identifier up to 40 characters long and ITEM is any of the following:

float, vector, color or string expressions objects (all kinds) texture, pigment, normal, finish or halo color_map, pigment_map, slope_map, normal_map camera, light_source atmosphere fog rainbow skysphere transform

Here are some examples.

#declare Rows = 5 #declare Count = Count+1 #declare Here = <1,2,3> #declare White = rgb <1,1,1> #declare Cyan = color blue 1.0 green 1.0 #declare Font_Name = "ariel.ttf" #declare Ring = torus {5,1} #declare Checks = pigment{ checker White, Cyan } object{Rod scale y*5} // not "cylinder{Rod}" object { Ring pigment {Checks scale 0.5} transform Skew }

Declarations, like most language directives, can appear anywhere in the file --- even within other statements. For example:

#declare Here=<1,2,3> #declare Count=0 // initialize Count union { object{Rod translate Here*Count} #declare Count=Count+1 // re-declare inside union object{Rod translate Here*Count} #declare Count=Count+1 // re-declare inside union object{Rod translate Here*Count} }

As this example shows, you can re-declare an identifier and may use previously declared values in that re-declaration. However if you attempt to re-declare an identifier as anything other than its original type, it will generate a warning message.

Declarations may be nested inside each other within limits. In the example in the previous section you could declare the entire union as a object. However for technical reasons you may not use any language directive inside the declaration of floats, vectors or color expressions.

Section 3.2.3
Default Directive

POV-Ray creates a default texture when it begins processing. You may change those defaults as described below. Every time you specify a texture {...} statement, POV-Ray creates a copy of the default texture. Anything you put in the texture statement overrides the default settings. If you attach a pigment, normal, or finish to an object without any texture statement then POV-Ray checks to see if a texture has already been attached. If it has a texture then the pigment, normal or finish will modify that existing texture. If no texture has yet been attached to the object then the default texture is copied and the pigment, normal or finish will modify that texture.

You may change the default texture, pigment, normal or finish using the language directive #default {...} as follows:

#default { texture { pigment {...} normal {...} finish {...} } }

Or you may change just part of it like this:

#default { pigment {...} }

This still changes the pigment of the default texture. At any time there is only one default texture made from the default pigment, normal and finish. The example above does not make a separate default for pigments alone. Note: Special textures tiles and material_map or a texture with a texture_map may not be used as defaults.

You may change the defaults several times throughout a scene as you wish. Subsequent #default statements begin with the defaults that were in effect at the time. If you wish to reset to the original POV-Ray defaults then you should first save them as follows:

//At top of file #declare Original_Default = texture {}

later after changing defaults you may restore it with...

#default {texture {Original_Default}}

If you do not specify a texture for an object then the default texture is attached when the object appears in the scene. It is not attached when an object is declared. For example:

#declare My_Object= sphere{<0,0,0>,1} // Default texture not applied object{My_Object} // Default texture added here

You may force a default texture to be added by using an empty texture statement as follows:

#declare My_Thing= sphere{<0,0,0>,1 texture{}} // Default texture applied

The original POV-Ray defaults for all items are given throughout the documentation under each appropriate section.

Section 3.2.4
Version Directive

While many language changes have been made for POV-Ray 3.0, all of version 2.0 syntax and most of version 1.0 syntax still works. Whenever possible we try to maintain backwards compatibility. One feature introduced in 2.0 that was incompatible with any 1.0 scene files is the parsing of float expressions. Setting +MV1.0 command line switch or the Version=1.0 INI option turns off expression parsing as well as many warning messages so that nearly all 1.0 files will still work. The changes between 2.0 and 3.0 are not as extensive. Setting Version=2.0 is only necessary to eliminate some warning messages. Naturally the default setting for this option is Version=3.0

The #version language directive is used to change modes within scene files. This switch or INI options only affects the initial setting.

Together with the built-in version identifier, the #version directive allows you to save and restore the previous values of this compatibility setting. For example suppose MYSTUFF.INC is in version 1.0 format. At the top of the file you could put:

#declare Temp_Vers = version // Save previous value #version 1.0 // Change to 1.0 mode ... // Version 1.0 stuff goes here ... #version Temp_Vers // Restore previous version

Previous versions of POV-Ray would not allow you to change versions inside an object or declaration but that restriction has been lifted for POV-Ray 3.0.

Future versions of POV-Ray may not continue to maintain full backward compatibility even with the #version directive. We strongly encourage you to phase in 3.0 syntax as much as possible.

Section 3.2.5
Conditional Directives

POV-Ray 3.0 allows a variety of new language directives to implement conditional parsing of various sections of your scene file. This is especially useful in describing the motion for animations but it has other uses as well. Also available is a #while loop directive. You may nest conditional directives 200 levels deep.

Section 3.2.5.1
IF ELSE Directives

The simplest conditional directive is a traditional #if directive. It is of the form...

#if (COND) // This section is // parsed if COND is true #else // This section is // parsed if COND is false #end // End of conditional part

where (COND) is a float expression that evaluates to a boolean value. A value of 0.0 is false and any non-zero value is true. Note that extremely small values of about 1e-10 are considered zero in case of round off errors. The parentheses around the condition are required. The #else directive is optional. The #end directive is required.

Section 3.2.5.2
IFDEF Directives

The #ifdef directive is similar to the #if directive however it is used to determine if an identifier has been previously declared. After the #ifdef directive instead of a boolean expression you put a lone identifier enclosed in parentheses. For example:

#ifdef (User_Thing) // This section is parsed if the // identifier "User_Thing" was // previously declared object{User_Thing} // invoke identifier #else // This section is parsed if the // identifier "User_Thing" was not // previously declared box{<0,0,0>,<1,1,1>} // use a default #end // End of conditional part

The #else directive is optional. The #end directive is required.

Section 3.2.5.3
SWITCH CASE & RANGE Directives

A more powerful conditional is the #switch directive. The syntax is as follows...

#switch (VALUE) #case (TEST_1) // This section is parsed if VALUE=TEST_1 #break //First case ends #case (TEST_2) // This section is parsed if VALUE=TEST_2 #break //Second case ends #range (LOW_1,HIGH_1) // This section is parsed if (VALUE>=LOW_1)&(VALUE<=HIGH_1) #break //Third case ends #range (LOW_2,HIGH_2) // This section is parsed if (VALUE>=LOW_2)&(VALUE<=HIGH_2) #break //Fourth case ends #else // This section is parsed if no other case or // range is true. #end // End of conditional part

The float expression VALUE following the #switch directive is evaluated and compared to the values in the #case or #range directives. When using #case, it is followed by a float expression TEST_1 in parentheses. It is compared to the VALUE. As usual in POV-Ray, float comparisons are considered equal if their difference is under 1e-10. If the values are equal, parsing continues normally until a #break, #else or #end directive is reached. If the comparison fails, POV-Ray skips until another #case or #range is found.

If you use the #range directive, it is followed by two float expressions LOW_1 and HIGH_1 which are enclosed in parentheses and separated by a comma. If the switch VALUE is in the range specified, then parsing continues normally until a #break, #else or #end directive is reached. If the VALUE is outside the range, the comparison fails and POV-Ray skips until another #case or #range is found.

If no #case or #range succeeds, the #else section is parsed. The #else directive is optional. If no #else is specified and no match succeeds, then parsing resumes after the #end directive.

There may be any number of #case or #range directives in any order you want. If a segment evaluates true but no #break is specified, the parsing will fall through to the next #case or #range and will continue until a #break, #else or #end. Hitting a #break while parsing a successful section causes an immediate jump to the #end so at most, one section of the directive is parsed even if more that one condition would be satisfied.

Next Section
Table Of Contents